API Method "check_message"

Required Parameters:

method_name — must be 'check_message';
auth_key — Access key. To obtain a key please get an account here: https://cleantalk.org/register;
sender_email — e-mail you want to check for spam;
sender_ip — IP you want to check for spam;
js_on — is JavaScript enabled in a user's browser or not;
submit_time — form submitting time in seconds.

Here is the list of the necessary parameters that heavily affect filtration. Most of the sent requests will be marked as spam without them:

all_headers — HTTP-request headers (JSON encoded);
sender_nickname — nickname you want to check for spam;
message — text of the message you want to check for spam, can contain HTML-tags;
sender_info — information about a sender, should be JSON encoded, next fields are mandatory:

REFFERRER — content of $_SERVER['HTTP_REFERER']
USER_AGENT — content of $_SERVER['HTTP_USER_AGENT']

Additional Parameters:

Sending these parameters will improve filtration.

sender_info — any additional information about a sender, should be JSON encoded.
post_info — additional information about message (JSON encoded, must contain key named 'comment_type');

Examples:

Using Wget:

wget -O- --post-data='{"method_name":"check_message","auth_key":"your_acccess_key","sender_email":"stop_email@example.com","sender_nickname":"John Doe","sender_ip":"127.0.0.1","js_on":1,"submit_time":15}' https://moderate.cleantalk.org/api2.0

Using PHP:

Download CleanTalk library here. Library folder must be placed in the same path as the PHP file.

Also, you can install the library via composer.

<?php
session_start();
 
require_once (dirname(__FILE__) . '/lib/Cleantalk.php');
require_once (dirname(__FILE__) . '/lib/CleantalkRequest.php');
require_once (dirname(__FILE__) . '/lib/CleantalkResponse.php');
require_once (dirname(__FILE__) . '/lib/CleantalkHelper.php');
 
// Take params from config
$config_url = 'http://moderate.cleantalk.org/api2.0/';
$auth_key = 'enter_your_key'; // Set Cleantalk auth key
 
if (count($_POST))
{
        $sender_nickname = 'John Dow';
        if (isset($_POST['login']) && $_POST['login'] != '')
                $sender_nickname = $_POST['login'];
 
        $sender_email = 'stop_email@example.com';
        if (isset($_POST['email']) && $_POST['email'] != '')
                $sender_email = $_POST['email'];
 
        $sender_ip = null;
        if (isset($_SERVER['REMOTE_ADDR']))
                $sender_ip = $_SERVER['REMOTE_ADDR'];
 
        $js_on = 0;
        if (isset($_POST['js_on']) && $_POST['js_on'] == date("Y"))
                $js_on = 1;
 
        $message = null;
        if (isset($_POST['message']) && $_POST['message'] != '')
                $message = $_POST['message'];
 
// The facility in which to store the query parameters
$ct_request = new /lib/CleantalkRequest();
$ct_request->auth_key = $auth_key;
$ct_request->agent = 'php-api';
$ct_request->sender_email = $sender_email;
$ct_request->sender_ip = $sender_ip;
$ct_request->sender_nickname = $sender_nickname;
$ct_request->js_on = $js_on;
$ct_request->message = $message;
$ct_request->submit_time = time() - (int) $_SESSION['ct_submit_time'];
 
//Additional parameters.
$ct = new libCleantalk();
$ct->server_url = $config_url;
 
//Check
$ct_result = $ct->isAllowMessage($ct_request);
        if ($ct_result->allow == 1)
                echo 'Message allowed. Reason ' . $ct_result->comment;
        else
                echo 'Message forbidden. Reason ' . $ct_result->comment;
        echo '<br /><br />';
}
else
        $_SESSION['ct_submit_time'] = time();
?>

HTML code:

<form method="post">
        <label for="login">Login:<label>
        <input type="text" name="login" id="login" /> <br />
        <label for="email">Email:<label>
        <input type="text" name="email" id="email" value="" /> <br />
        <label for="message">Message:<label>
        <textarea name="message" id="message"></textarea> <br />
        <input type="hidden" name="js_on" id="js_on" value="0" />
        <input type="submit" />
        </form>
<script type="text/javascript">
var date = new Date(); document.getElementById("js_on").value = date.getFullYear();
</script>

Submit_time and js_on parameters are very important for proper checking. Submit_time is the difference between submitting form time and page accessing time. Js_on can be calculated by evaluating some JavaScript code in browser and comparing with reference value on server side. See in example, how you can calculate them: https://cleantalk.org/help/api-without

Example of additional parameters usage (PHP):

$sender_info = array(
        'page_url' =>htmlspecialchars(@$_SERVER['SERVER_NAME'].@$_SERVER['REQUEST_URI']),
        'REFFERRER' => htmlspecialchars(@$_SERVER['HTTP_REFERER']),
        'USER_AGENT' => htmlspecialchars(@$_SERVER['HTTP_USER_AGENT']),
        'fields_number' => sizeof($_POST),
);
$sender_info = json_encode($sender_info);
        if ($sender_info === false) $sender_info = '';
$ct_request->sender_info = $sender_info;
$ct_request->all_headers = json_encode(apache_request_headers());
$post_info['comment_type'] = 'general_comment';
$post_info = json_encode($post_info);
        if ($post_info === false) $post_info = '';
$ct_request->post_info = $post_info;

More info can be found on our GitHub.

Response:

Server's response is independent of the platform.

{
"stop_queue" : 0,
"inactive" : 0,
"version" : "7.47",
"spam" : 1,
"js_disabled" : 0,
"comment" : "*** Forbidden. Sender blacklisted. ***",
"codes" : "FORBIDDEN BL",
"blacklisted" : 1,
"fast_submit" : 0,
"account_status" : "1",
"id" : "433289e278ae059f8fc58914fc890de2",
"allow" : 0
}

Explanation:

stop_queue — stop queue for comment approvement (comment is a 100% spam);
spam — spam, possible to send it to manual moderation if flag stop_queue == 0;
js_disabled — JavaScript is disabled;
comment — comment of server's decision or of other errors (wrong Access key etc.);
codes — answer codes;
blacklisted — sender is in the CleanTalk Blacklists;
fast_submit — too fast form submitting;
account_status — is account enabled or not (0 or 1);
id — message ID (helpful for our support);
allow — is message allowed (1) or not (0).

The rest is information flags for displaying appropriate messages to site visitors.

In the server response code, you can also see the result of checking an email address for existence. If a blocked request contains a non-existent e-mail address, you will see the next text in the API response code field: "FORBIDDEN EMAIL_NOT_EXISTS"

Please note, this code will be displayed only if a non-existent email is the main reason for blocking.

You could see the details of the codes at the bottom of this article: https://cleantalk.org/help/api-without.

Available features:

CleanTalk's Personal Blacklist or Whitelist feature helps you to block unwanted users and to allow users that were recognized as spammers.
Stop-Word feature allows you to block comments and nicknames that contain any word from your Stop-Word List.
Country Blacklist allows you to block all comments and registration coming from selected countries.

Notice: Stop-Word and Country Blacklist features are available after purchasing our Extra Package. Go to your Renewal License Page to see the details.

Method CHECK_MESSAGE should be used to check comments and contact form submissions for spam. For other purposes you could use other methods:

check_newuser (requires Standard Anti-Spam License) — Registration check.
send_feedback (requires Standard Anti-Spam License) — Send feedback to CleanTalk.
spam_check (requires Blacklist API License) — Bulk IP and e-mail check for spam activity.
backlinks_check (requires Blacklist API License) — Mass check for backlinks in spam comments.
Nginx Anti-Spam Module - check all POST requests for spam
Universal Anti-Spam Plugin - this plugin can be installed on any custom website or CMS.

If you haven't found the answer to your question, please, contact our support team:

https://cleantalk.org/my/support/open

Create an account

Your CleanTalk Dashboard